home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Tools & Apps / Testing & Debugging / VUAssist 1.0d10 / READ ME FIRST!
Encoding:
Text File  |  1991-09-10  |  9.8 KB  |  227 lines  |  [TEXT/MPS ]

  1. **************************************************************************
  2. What is VUAssist For MacApp 3.0b2PQR?
  3. **************************************************************************
  4. The code contained in this folder is the source code for a MacApp 3.0b2PQR 
  5. compatible version of VUAssist.  VUAssist is a Virtual User assistance module
  6. for MacApp applications.  By building VUAssist into your MacApp application, 
  7. you will be able to manipulate the user interface of your application very 
  8. easily with Virtual User.  
  9.  
  10. The version of VUAssist which is shipped with the Virtual User 1.0 and 1.1 
  11. packages is MacApp 2.0.x compatible.  This version of VUAssist has the same
  12. functionality as the 2.0.x compatible version which will ship with V.U. 1.1
  13. final.  It has been revved solely to make it compatible with MacApp 3.0b2PQR.
  14.  
  15. More information on VUAssist, including how to use it, is given below.
  16.  
  17. **************************************************************************
  18. VUAssist, The V.U. Assistance Module for MacApp Applications
  19. **************************************************************************
  20.  
  21. In order to find the location of items in windows for V.U., Agent VU peruses 
  22. the content list of windows and the item list of dialogs.  For applications 
  23. which are not built with MacApp, these data structures can be accessed via 
  24. global variables by Agent VU.  For MacApp applications, however, items in 
  25. windows are subclasses of the class TView, which are not available to the 
  26. Agent via global data structures.   As a result, Agent VU can’t provide any 
  27. information about these items to V.U. in the normal way.
  28.  
  29. To work around this problem, Agent VU provides a hook which allows an 
  30. application to assist Agent VU by providing information about itself.  
  31. In this folder, we’ve provided VUAssist, an assistance module for MacApp 
  32. applications which can be hooked onto Agent VU to provide information about 
  33. a MacApp application. A user can build a MacApp application with VUAssist 
  34. and then test the application with V.U..  V.U. will "recognize" many of the
  35. application's views which translate into standard user interface items: buttons,
  36. scroll bars, checkboxes, static text, editable text fields, popup menus, etc.
  37.  
  38. The module exists as a unit called UVUAssist.  The unit consists of four files:   
  39. VUAssist.p, VUAssist.inc1.p, VUAssist.inc2.p, and VUAssist.a.
  40.  
  41.  
  42. -----------------------------------------------------------------------------
  43. What's New in this Version - 1.0d10
  44. -----------------------------------------------------------------------------
  45.  
  46. 1) VUAssist has now been defined as a descendant of TEvtHandler.  This allows 
  47. VUAssist to be installed as a cohandler.  The frequency with which VUAssist's 
  48. DoIdle routine is called can now be controlled. This gives the user of VUAssist 
  49. a convenient way to control the responsiveness of the application to Virtual User.
  50.  
  51. 2) VUAssist's handling of TGridView objects has changed somewhat.  The cells of TGridView 
  52. objects now appear as "contentItems" to V.U. as opposed to "userItems".  This is more
  53. consistent with V.U.'s interface item hierarchy.  Useritems are really intended to describe
  54. Dialog Manager userItems while contentItems are effectively the "base class" of all interface
  55. items in V.U..  Since there is no class of interface items in V.U. which is intended to describe
  56. the cells of gridviews, they should be considered to belong to the "base class", contentItem.
  57.  
  58. 3) The feature of VUAssist which maps the cells of gridviews to "contentitems" can be disabled 
  59. through the boolean gridItemSupport argument to the IVUAssist method.
  60.  
  61. 4) The implementation of some of the methods of VUAssist have been modified to improve 
  62. performance.
  63.  
  64. !!!!! NOTICE !!!!!
  65. 5) The instructions for building VUAssist into your application have changed 
  66. slightly since the 1.0d7 version, which was shipped with V.U. 1.0 final.  Therefore the 
  67. instructions given in the Virtual User General Reference are not valid for this version.
  68. The new instructions are given below.
  69.  
  70.  
  71. -----------------------------------------------------------------------------
  72. How to Use VUAssist
  73. -----------------------------------------------------------------------------
  74.  
  75. To build VUAssist into your MacApp application, follow the instructions
  76. below.  
  77.  
  78. For applications written in Object Pascal:
  79.  
  80. 1)  Modify your MAMake file to include the following:
  81.  
  82.     •    add the following to the list of OtherInterfaces
  83.         
  84.         "{SrcApp}UVUAssist.a" ∂
  85.         "{SrcApp}UVUAssist.p" ∂
  86.         
  87.     •    add the following to the list of OtherLinkFiles
  88.         
  89.         "{ObjApp}UVUAssist.a.o" ∂
  90.         "{ObjApp}UVUAssist.p.o" 
  91.     
  92.     •    add the additional dependency:
  93.  
  94.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  95.                     "{SrcApp}UVUAssist.p" ∂
  96.                     "{SrcApp}UVUAssist.inc1.p" ∂
  97.                     "{SrcApp}UVUAssist.inc2.p" ∂
  98.                     {MacAppIntf} ∂
  99.                     {BuildingBlocksIntf}
  100.                             
  101. 2)     Modify or subclass your descendant of TApplication to do the following:
  102.                             
  103.     •    In MyApplication.IApplication, you must execute this:
  104.             NEW(gVUAssist);
  105.             FailNil(gVUAssist);
  106.             gVUAssist.IVUAssist(gridItemSupport); { gridItemSupport must be a boolean expression.
  107.                                                     see "Altering the behavior of VUAssist
  108.                                                     for an explanation of gridItemSupport }
  109.     •    In MyApplication.AboutToLoseControl you must execute this:
  110.             gVUAssist.SuspendMole;
  111.  
  112.     •    In MyApplication.RegainControl you must execute this:
  113.             gVUAssist.ResumeMole;
  114.  
  115.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  116.             SELF.InstallCohandler(gVUAssist,false);
  117.  
  118. 3)    Include the unit UVUAssist in your USES clause where appropriate.  Other units may 
  119.     need to be included along with UVUAssist if they are not already.
  120.  
  121.  
  122. For applications written in C++:
  123.  
  124. 1)  Modify your MAMake file to include the following:
  125.  
  126.     •    add the following to the list of OtherInterfaces
  127.         
  128.         "{SrcApp}UVUAssist.a" ∂
  129.         "{SrcApp}UVUAssist.p" ∂
  130.         "{SrcApp}UVUAssist.h"
  131.         
  132.     •    add the following to the list of OtherLinkFiles
  133.         
  134.         "{ObjApp}UVUAssist.a.o" ∂
  135.         "{ObjApp}UVUAssist.p.o" 
  136.     
  137.     •    add the additional dependency:
  138.  
  139.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  140.                     "{SrcApp}UVUAssist.p" ∂
  141.                     "{SrcApp}UVUAssist.inc1.p" ∂
  142.                     "{SrcApp}UVUAssist.inc2.p" ∂
  143.                     {MacAppIntf} ∂
  144.                     {BuildingBlocksIntf}
  145.                             
  146. 2)     Modify or subclass your descendant of TApplication to do the following:
  147.                             
  148.     •    In MyApplication.IApplication, you must execute this:
  149.             gVUAssist = new TVUAssist;
  150.             FailNIL(gVUAssist);
  151.             gVUAssist->IVUAssist(gridItemSupport); /* gridItemSupport must be a boolean expression.
  152.                                                       see "Altering the behavior of VUAssist
  153.                                                       for an explanation of gridItemSupport */
  154.  
  155.     •    In MyApplication.AboutToLoseControl you must execute this:
  156.             gVUAssist->SuspendMole();
  157.  
  158.     •    In MyApplication.RegainControl you must execute this:
  159.             gVUAssist->ResumeMole();
  160.  
  161.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  162.             this->InstallCohandler(gVUAssist,false);
  163.  
  164. 3)    Include the header file UVUAssist.h where appropriate.
  165.  
  166.         #ifndef __UVUASSIST__
  167.         #include "UVUAssist.h"
  168.         #endif
  169.         
  170.  
  171. 4)    If you are using C++, make sure to use the VUAssist.a file which is included in the 
  172.     folder "C++ Interface to VUAssist" in place of the file with the same name which is 
  173.     found in the folder "VUAssist Source Code".
  174.  
  175.  
  176. -----------------------------------------------------------------------------
  177. Modifying the Behavior of VUAssist
  178. -----------------------------------------------------------------------------
  179.  
  180. 1) VUAssist Idle Frequency
  181.  
  182. VUAssist has now been defined to be a descendant of TEvtHandler (or TEventHandler in
  183. MacApp 3.0).  An application's responsiveness to V.U. queries can be controlled by 
  184. setting the idle frequency of VUAssist. Although nothing is done with this idle time, 
  185. it forces the application to awaken and call SystemTask with the application's context 
  186. switched in.  This is necessary for Agent VU, a driver, to get processing time.  Agent VU, 
  187. in turn, calls VUAssist.  So, in a roundabout way, the application's responsiveness to V.U. 
  188. can be controlled by setting the idle frequency of VUAssist.
  189.  
  190. By default, the time of VUAssist has been set to 1, the near maximum frequency.  
  191. You may want to alter this by executing the following statement:
  192.  
  193. gVUAssist.SetIdleFreq(newIdleFreq);
  194.  
  195. Note, however, that larger values of VUAssist's idle frequency will slow down the application's
  196. response to V.U. unless there is another cohandler with a very high idle frequency.
  197.  
  198.  
  199. 2) The gridItemSupport Argument
  200.  
  201. Note that the TVUAssist method IVUAssist now takes an argument, gridItemSupport.  This
  202. argument, if true, enables an optional feature of VUAssist where the cells of gridviews are
  203. recognized as individual user interface items by V.U..  Virtual User does not yet have a 
  204. gridview or list descriptor.  So, for the short term, the "gridItemSupport" feature treats
  205. each cell of a gridview as a "contentitem" in the V.U. scripting language.
  206.  
  207. In applications with very large gridviews, it may not be desirable to treat each cell in a
  208. gridview as a separate item in V.U..  This may hamper performance.  By setting the value of
  209. the gridItemSupport argument to false, you will disable V.U.'s griditem support feature 
  210. and the cells of gridviews will not be seen as "contentItems" by V.U..  The cells will 
  211. be "invisible" to Virtual User.
  212.  
  213. **** WARNING!! ********************************************************************
  214. If the "gridItemSupport" feature is enabled, the following rules MUST be followed:
  215.  
  216. 1) Any descendants of TTextGridView in your application MUST override the method 
  217. TTextGridView.GetText.  This method is called by VUAssist to obtain the text associated 
  218. with a gridview cell. TTextGridView.GetText is a method which must be overridden in MacApp. 
  219.  
  220. 2) For reasons analogous to those above, any descendants of TTextListView in your 
  221. application MUST override the method TTextListView.GetItemText.  TTextListView.GetText 
  222. need not be overridden.
  223. ************************************************************************************
  224.  
  225.  
  226.  
  227.